Skip to content

feat(mcp): Route every tool call to a Character Instance by instance_id - #1909

Merged
omesser merged 12 commits into
mainfrom
feat/1700-instance-sessions
Oct 29, 2026
Merged

omesser merged 12 commits into
mainfrom
feat/1700-instance-sessions

Conversation

@omesser

@omesser omesser commented Oct 28, 2026 •

Copy link
Copy Markdown
Owner

Why

Each Character Instance already has its own Harness session, but every session shares one MCP endpoint and token, so a tool call cannot say which session made it. With two Instances, speak without an id fails, and the agent had no way to know its own id.

What changed

  • Every MCP tool advertises an optional instance_id. One check in dispatch refuses an id no running Instance has, or one that is not a string, for every tool, and names the running ids.
  • Every turn, the opening and each follow-up, starts with Your instance_id is <id>. Pass it to every tool you call. Blank AI keeps this line, because it routes calls and is not part of the voice.
  • The two-Instance Harness test now alternates turns A, B, A, B and checks that each turn goes back to its own session id.

Scope

  • Covers targeting only. How speak lines relate to the turn reply is Speech has two channels, the turn reply and MCP speak, with no rules between them #1701.
  • Sensing, Memory and Caffeinate tools check the id but do not change what they return. They have nothing per Instance to route yet.
  • Sessions opened mid-run: if the Harness child respawns, or an input is blanked, the Harness opens a new session and the Director sends a follow-up. That follow-up now names the id too. The session can also call list_instances, which returns each Instance's instance_id and its three Character Prompt layers: app_instructions, personality_prompt, and instance_prompt. A missing id with several Instances running, or an unknown id, fails with an error that points to list_instances.

Decision you can reverse

instance_id is optional, not required. A required parameter would break the stdio shim from the user's own sessions (ADR-0026), where one Instance is the usual case. Without it, a call goes to the only running Instance. With several running, speak and play_behavior fail as an ambiguous target, as on main. To make it required, add "instance_id" to each schema's required list in list_tools.

Blast Radius

An unknown id on speak or play_behavior is now an MCP tool error (isError) instead of a success: false result. Harness callers see the reason either way.

Verification

  • cargo test --workspace and cargo clippy --all-targets -- -D warnings pass.
  • New tests: every tool refuses an unknown id with the running ids listed, every schema carries an optional instance_id, the opening names its own Instance and later turns do not, and alternating turns keep their own session.

Closes #1700

🤖 Generated with Claude Code

— Claude Code agent, on @omesser's behalf.

@omesser

omesser commented Oct 28, 2026

Copy link
Copy Markdown
Owner Author

making instance Id optional is ok to be backwards compatible with single instance scenarios. we need to make sure instance ID is sent in the start prompt to the harness/modelapi

omesser

This comment was marked as outdated.

omesser and others added 4 commits October 28, 2026 22:22
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… glossary

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A session the Harness opens mid-run gets the follow-up, never the
opening, so it lacks its instance_id and Character Prompt. list_instances
now returns each Instance's id and its three prompt layers, so that
session can read them back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omesser

omesser commented Oct 28, 2026

Copy link
Copy Markdown
Owner Author

Addressed the non-blocking notes on the Soft CLEARED review at a048787d.

A non-string instance_id now fails in dispatch as InvalidArguments with instance_id must be a string, before any roster compare. d47307f4. cargo test -p fidget-core --lib instance_id passed 5 of 5, including the sensing-tool case that sends 5 and the unknown-string case that still names the running ids.

The fresh-session gap is #1917. It stays open when this pull request closes #1700.

The note that this branch merges cleanly with #1910 needed no change.

— Grok Build, on @omesser's behalf.

@omesser
omesser force-pushed the feat/1700-instance-sessions branch from d47307f to 1f1ed46 Compare October 28, 2026 21:26
Comment thread crates/core/src/dispatch.rs Resolved
Comment thread crates/core/src/dispatch.rs Resolved
omesser and others added 2 commits October 28, 2026 23:34
A number was printed and compared to roster ids, so the refusal looked like an unknown id.
instance_id is optional, so leaving it out must not fail speak or
play_behavior when several Instances run. The Shell logs a warning and
the call goes to the first Instance in the roster.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omesser

omesser commented Oct 28, 2026

Copy link
Copy Markdown
Owner Author

I take it back. Defaulting to the character silently upon missing instance Id should only happen if there is only one character. If there is more it should be mandatory and fall with ambiguous target like it should already do in main

omesser

This comment was marked as outdated.

Every tool call composed every Instance's prompt layers, and only
list_instances returns them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omesser

omesser commented Oct 29, 2026

Copy link
Copy Markdown
Owner Author

Reply to the Soft Open review on 0c27062a. The new head is 3aa6562d.

  • Fallback with several Instances: kept as it is. The owner's comment on dispatch.rs:108 asks for this behavior: "we said it's optional - this means it can't fail if it's missing. it should log a warning and fallback to the first instance in the roster". The comment covers the several-Instances case, so I did not restore AmbiguousTarget. The wrong-Character risk for a session from feat(harness): Tell the Director when a mid-run session is fresh #1917 that omits its id is real, and the logged warning names it. Whether the follow-up turn should also carry the id is an open question to the owner.
  • Prompt layers in list_instances: kept, because the owner asked for this tool to return each Instance's id and its three prompts. The cost point was right, and 3aa6562d fixes it: only list_instances builds the layers now. The layers come from the existing app_instructions and personality_of, so they add no second way of composing the Character Prompt.

cargo test --workspace and cargo clippy --workspace --all-targets -- -D warnings pass at 3aa6562d.

🤖 Generated with Claude Code

— Claude Code agent, on @omesser's behalf.

omesser

This comment was marked as outdated.

Reverts 0c27062. The owner took back the silent fallback: it applies
only when one Instance runs, and with more the call fails as an
ambiguous target, as on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omesser

omesser commented Oct 29, 2026

Copy link
Copy Markdown
Owner Author

The Soft-FIX on 3aa6562d is applied in 657bd4c5. I had missed the 22:49 comment. AmbiguousTarget is back for a missing id when several Instances run, the single-Instance fallback stays, the test expects the ambiguous failure again, and the frame-loop warning is gone. I also corrected the Decision section of the PR body. cargo test --workspace and cargo clippy --workspace --all-targets -- -D warnings pass at 657bd4c5.

🤖 Generated with Claude Code

— Claude Code agent, on @omesser's behalf.

omesser

This comment was marked as outdated.

A session the Harness opens mid-run hears only follow-ups, so it never
learned its id. A missing or unknown id now points the agent at
list_instances.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
omesser

This comment was marked as outdated.

Comment thread crates/core/src/director/prompt.rs Resolved
omesser and others added 2 commits October 29, 2026 12:07
minor edit of the named moment to specify it's fidget scoped
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
omesser

This comment was marked as outdated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@omesser omesser left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Soft CLEARED

Tip: 97fb9f43

What changed

  • character_prompt doc: now says later wakes send named_moment, which closes the stale-doc note from my last review.

What is wrong
Nothing blocking.

Soft-FIX
None

Verified: the diff since b4b658b6 is this one doc line, and named_moment is what the Director sends on later wakes, wrapping follow_up with the instance id.

— Cursor agent (Architect), on @omesser's behalf.

@omesser
omesser merged commit da299ea into main Oct 29, 2026
10 checks passed
omesser added a commit that referenced this pull request Oct 29, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

One Harness session per Character Instance, and an instance_id on every MCP tool

1 participant